////////////////////////////////////////////////////////////////////////////////
// Copyright 2010 Michael Schmalle - Teoti Graphix, LLC
// 
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
// 
// http://www.apache.org/licenses/LICENSE-2.0 
// 
// Unless required by applicable law or agreed to in writing, software 
// distributed under the License is distributed on an "AS IS" BASIS, 
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and 
// limitations under the License
// 
// Author: Michael Schmalle, Principal Architect
// mschmalle at teotigraphix dot com
////////////////////////////////////////////////////////////////////////////////

package org.teotigraphix.swizplugin.api
{

/**
 * A memento interface used for saving and loading state.
 * 
 * @author Michael Schmalle
 * @copyright Teoti Graphix, LLC
 * @productversion 1.0
 */
public interface IMemento
{
	//--------------------------------------------------------------------------
	//
	//  Methods
	//
	//--------------------------------------------------------------------------
	
	/**
	 * Creates a new child named type on the element.
	 * 
	 * @param type A String naming the new child.
	 * @param id The optional id of the child.
	 * @return An IMemento instance representing the new child.
	 */
	function createChild(type:String, id:String = null):IMemento;
	
	/**
	 * Returns the first child found named type.
	 * 
	 * <p>If no child is found, returns null.</p>
	 * 
	 * @param type A String child type.
	 * @return An IMemento instance representing the child.
	 */
	function getChild(type:String):IMemento;
	
	/**
	 * Returns the first child who's id matches the id passed.
	 * 
	 * @param id A unique String id to compare with the children.
	 * @return An IMemento instance representing the child.
	 */
	function getChildByID(id:String):IMemento;
	
	/**
	 * Returns the first child who's name property matches the name passed.
	 * 
	 * @param id A unique String name to compare with the children.
	 * @return An IMemento instance representing the child.
	 */
	function getChildByName(id:String):IMemento;
	
	/**
	 * Returns all children of type as an Array of IMemento.
	 * 
	 * <p>Returns an empty Array if no children of type are found.</p>
	 * 
	 * @param type A String child type.
	 * @return An Array of IMemento for the specified type.
	 */
	function getChildren(type:String):Array; // of IMemento
	
	/**
	 * Returns the id found on this memento.
	 * 
	 * @return A String id if found.
	 */
	function getID():String;
	
	/**
	 * Returns a typed Boolean value for the key.
	 * 
	 * @return A Boolean.
	 */
	function getBoolean(key:String):Boolean;
	
	/**
	 * Returns a typed Number value for the key.
	 * 
	 * @return A Number.
	 */
	function getFloat(key:String):Number;
	
	/**
	 * Returns a typed int value for the key.
	 * 
	 * @return A int, NaN if the value is null.
	 */
	function getInteger(key:String):int;
	
	/**
	 * Returns a typed String value for the key.
	 * 
	 * @return A String.
	 */
	function getString(key:String):String;
	
	/**
	 * Returns a String value for the entire element.
	 * 
	 * @return A String.
	 */
	function getTextData():String;
	
	/**
	 * Puts a Boolean value on the element.
	 * 
	 * @param key A String name for the value.
	 * @param value The Boolean to put.
	 */
	function putBoolean(kley:String, value:Boolean):void;
	
	/**
	 * Puts a Number value on the element.
	 * 
	 * @param key A String name for the value.
	 * @param value The Number to put.
	 */
	function putFloat(kley:String, value:Number):void;
	
	/**
	 * Puts a int value on the element.
	 * 
	 * @param key A String name for the value.
	 * @param value The int to put.
	 */
	function putInteger(key:String, value:int):void;
	
	/**
	 * Puts a String value on the element.
	 * 
	 * <p>If the String value is null, the element will not recieve the key.</p>
	 * 
	 * @param key A String name for the value.
	 * @param value The String to put.
	 */
	function putString(key:String, value:String):void;
	
	/**
	 * Puts text data on the element.
	 * 
	 * <p>If the String value is null, the element will not recieve the data.</p>
	 * 
	 * @param value A String of data that will be held by the element.
	 */
	function putTextData(value:String):void;
	
	/**
	 * Puts an IMemento into this memento.
	 * 
	 * @param memento An IMemento to put on this memento.
	 */
	function putMemento(memento:IMemento):void;
	
	/**
	 * In place replacement of the memento.
	 * 
	 * @param memento An IMemento to put on this memento.
	 */ 
	function replaceMemento(memento:IMemento):void;
}
}